Button

Kind of class:class
Inherits from:UIComponent < MovieClip
Known subclasses:
Classpath:gfx.controls.Button
File last modified:Wednesday, 30 June 2010, 09:09:04
Buttons are the foundation component of the CLIK framework and are used anywhere a clickable interface control is required. The default Button class (gfx.controls.Button) supports a textField to display a label, and states to visually indicate user interaction. Buttons can be used on their own, or as part of a composite component, such as ScrollBar arrows or the Slider thumb. Most interactive components that are click-activated compose or extend Button.

The CLIK Button is a general purpose button component, which supports mouse interaction, keyboard interaction, states and other functionality that allow it to be used in a multitude of user interfaces. It also supports toggle capability as well as animated states. The ToggleButton, AnimatedButton and AnimatedToggleButton provided in the Button.fla component source file all use the same base component class.

Inspectable Properties
The inspectable properties of the Button component are:
  • label: Sets the label of the Button.
  • toggle: Sets the toggle property of the Button. If set to true, the Button will act as a toggle button.
  • visible: Hides the button if set to false.
  • disabled: Disables the button if set to true.
  • disableFocus: By default buttons receive focus for user interactions. Setting this property to true will disable focus acquisition.
  • disableConstraints: The Button component contains a constraints object that determines the placement and scaling of the textField inside of the button when the component is resized. Setting this property to true will disable the constraints object. This is particularly useful if there is a need to resize or reposition the button's textField via a timeline animation AND the button component is never resized. If not disabled, the textField will be moved and scaled to its default values throughout its lifetime, thus nullifying any textField translation/scaling tweens that may have been created in the button's timeline.
  • autoSize: Determines if the button will scale to fit the text that it contains and which direction to align the resized button. Setting the autoSize property to autoSize="none" will leave its current size unchanged.
  • enableInitCallback: If set to true, _global.CLIK_loadCallback() will be fired when a component is loaded and _global.CLIK_unloadCallback will be called when the component is unloaded. These methods receive the instance name, target path, and a reference the component as parameters. _global.CLIK_loadCallback and _global.CLIK_unloadCallback should be overriden from the game engine using GFx FunctionObjects.
  • soundMap: Mapping between events and sound process. When an event is fired, the associated sound process will be fired via _global.gfxProcessSound, which should be overriden from the game engine using GFx FunctionObjects.
States
The CLIK Button component supports different states based on user interaction. These states include
  • an up or default state.
  • an over state when the mouse cursor is over the component, or when it is focused.
  • a down state when the button is pressed.
  • a disabled state.
These states are represented as keyframes in the Flash timeline, and are the minimal set of keyframes required for the Button component to operate correctly. There are other states that extend the capabilities of the component to support complex user interactions and animated transitions, and this information is provided in the Getting Started with CLIK Buttons document.

Events
All event callbacks receive a single Object parameter that contains relevant information about the event. The following properties are common to all events.
  • type: The event type.
  • target: The target that generated the event.
The events generated by the Button component are listed below. The properties listed next to the event are provided in addition to the common properties.
  • show: The visible property has been set to true at runtime.
  • hide: The visible property has been set to false at runtime.
  • focusIn: The button has received focus.
  • focusOut: The button has lost focus.
  • select: The selected property has changed.
    • selected: The selected state of the Button, true for selected. Boolean type.
  • stateChange: The button's state has changed.
    • state: The Button's new state. String type, Values "up", "over", "down", etc.
  • rollOver: The mouse cursor has rolled over the button.
    • controllerIdx: The index of the controller used to generate the event (Applicable only for multi-controller environments). Number type. Values 0 to 3 (max 15).
  • rollOut: The mouse cursor has rolled out of the button.
    • controllerIdx: The index of the controller used to generate the event (Applicable only for multi-controller environments). Number type. Values 0 to 3 (max 15).
  • press: The button has been pressed.
    • controllerIdx: The index of the controller used to generate the event (applicable only for multi-controller environments). Number type. Values 0 to 3 (max 15).
  • doubleClick: The button has been double clicked. Only fired when the doubleClickEnabled property is set.
    • controllerIdx: The index of the controller used to generate the event (applicable only for multi-controller environments). Number type. Values 0 to 3 (max 15).
  • click: The button has been clicked.
    • controllerIdx: The index of the controller used to generate the event (applicable only for multi-controller environments). Number type. Values 0 to 3 (max 15).
  • dragOver: The mouse cursor has been dragged over the button (while the left mouse button is pressed).
    • controllerIdx: The index of the controller used to generate the event (applicable only for multi-controller environments). Number type. Values 0 to 3 (max 15).
  • dragOut: The mouse cursor has been dragged out of the button (while the left mouse button is pressed).
    • controllerIdx: The index of the controller used to generate the event (applicable only for multi-controller environments).Number type. Values 0 to 3 (max 15).
  • releaseOutside: The mouse cursor has been dragged out of the button and the left mouse button has been released.
    • controllerIdx: The index of the controller used to generate the event (applicable only for multi-controller environments).Number type. Values 0 to 3 (max 15).
Component metadata:
    InspectableList
    "autoSize"
    "disableConstraints"
    "disableFocus"
    "disabled"
    "enableInitCallback"
    "labelID"
    "soundMap"
    "toggle"
    "visible"

    Summary


    Constructor
    Instance properties
    • data
      • Data related to the button.
    • state
      • The mouse state of the button.
    • toggle
      • A button with a toggle value of true will change its selected state when the button is "clicked".
    • doubleClickEnabled
      • Determines if the component dispatches double-click events.
    • autoRepeat
      • Determines if the button dispatches "click" events when pressed down and held.
    • lockDragStateChange
      • Locks drag over and drag out state changes.
    • soundMap
      • Mapping between events and sound process
    • textField
      • A reference to the textField in the component.
    • focusIndicator
      • A reference to a MovieClip that is used to denote focus.
    • labelID
      • Set the label parameter of the component using the Locale class to look up a localized version of the text from the Game Engine.
    • label
      • The ActionScript-only label parameter that sets the text directly, and assumes localization has been handled externally.
    • disabled
      • Disable this component.
    • selected
      • Set the selected state of the Button.
    • groupName
      • The name of the group that the button belongs to.
    • group
      • A reference to the ButtonGroup instance that the button belongs to.
    • disableFocus
      • Disable focus management for the component.
    • disableConstraints
      • Disable constraints for the component.
    • autoSize
      • Determines if the button will scale to fit the text that it contains.
    Instance properties inherited from UIComponent
    __height __width _disabled _displayFocus _focused addEventListener cleanUpEvents disabled dispatchEvent displayFocus enableInitCallback focused focusHandlerReference focusTarget hasEventListener height initialized invalidationIntervalID removeAllEventListeners removeEventListener sizeIsInvalid soundMap visible width
    Class methods
    Class methods inherited from UIComponent
    createInstance
    Instance methods
    • setSize
      • Sets the width and height of the component at the same time using internal sizing mechanisms.
    • handleInput
      • Handle input from the game, via controllers or keyboard.
    Instance methods inherited from UIComponent
    changeFocus configUI dispatchEventAndSound dispatchEventToGame draw handleInput initSize invalidate onLoad onLoadImpl onMouseWheel onUnload scrollWheel setSize toString validateNow

    Constructor

    Button

    function Button (
    )

    The constructor is called when a Button or a sub-class of Button is instantiated on stage or by using attachMovie() in ActionScript. This component can not be instantiated using new syntax. When creating new components that extend Button, ensure that a super() call is made first in the constructor.

    Instance properties

    autoRepeat

    autoRepeat:Boolean = false
    (read,write)

    Determines if the button dispatches "click" events when pressed down and held.

    autoSize

    autoSize:String
    (read,write)

    Determines if the button will scale to fit the text that it contains. Setting the autoSize property to autoSize="none" will leave its current size unchanged.

    data

    data:Object
    (read,write)

    Data related to the button. This property is particularly helpful when using butons in a ButtonGroup.

    disableConstraints

    disableConstraints:Boolean
    (read,write)

    Disable constraints for the component. Setting the disableConstraintsproperty to disableConstraints=true will remove constraints from the textfield. This is useful for components with timeline based textfield size tweens, since constraints break them due to a Flash quirk.

    disabled

    disabled:Boolean
    (read,write)

    Disable this component. Focus (along with keyboard events) and mouse events will be suppressed if disabled.

    disableFocus

    disableFocus:Boolean
    (read,write)

    Disable focus management for the component. Setting the disableFocus property to disableFocus=true will remove support for tab key, direction key and mouse button based focus changes.

    doubleClickEnabled

    doubleClickEnabled:Boolean = false
    (read,write)

    Determines if the component dispatches double-click events.

    focusIndicator

    focusIndicator:MovieClip
    (read,write)

    A reference to a MovieClip that is used to denote focus. It can either have one frame (which will cause the Button to show/hide this focus movie by toggling its visibility), or have two named frames: show and hide, which will be played appropriately.

    group

    group:Object
    (read,write)

    A reference to the ButtonGroup instance that the button belongs to. The group is usually created in the parent clip of the button, so buttons in the same MovieClip scope with the same name can behave as a group. ButtonGroups will only be created in the parent scope when automatically created.
    See also:

    groupName

    groupName:String
    (read,write)

    The name of the group that the button belongs to. If the group does not exist, it is created in the parent of the button so that other buttons with the same group name can belong to the same group.
    See also:

    label

    label:String
    (read,write)

    The ActionScript-only label parameter that sets the text directly, and assumes localization has been handled externally.

    labelID

    labelID:String
    (read,write)

    Set the label parameter of the component using the Locale class to look up a localized version of the text from the Game Engine. This property can be set with ActionScript, and is used when the label is set using the Component Inspector.

    lockDragStateChange

    lockDragStateChange:Boolean = false
    (read,write)

    Locks drag over and drag out state changes. Useful for scrollbar and slider thumbs.

    selected

    selected:Boolean
    (read,write)

    Set the selected state of the Button. Buttons can have two sets of mouse states, a selected and unselected. When a Button's toggle property is true the selected state will be changed when the button is clicked, however the selected state can be set using ActionScript even if the toggle property is false.

    soundMap

    soundMap:Object = { theme:"default", focusIn:"focusIn", focusOut:"focusOut", select:"select", rollOver:"rollOver", rollOut:"rollOut", press:"press", doubleClick:"doubleClick", click:"click" }
    (read,write)

    Mapping between events and sound process

    state

    state:String = "up"
    (read,write)

    The mouse state of the button. Mouse states can be "over", "down", "up", and "release".

    textField

    textField:TextField
    (read,write)

    A reference to the textField in the component. The textField is an optional element. Note that when state changes are made, the textField instance may change, so changes made to it externally may be lost.

    toggle

    toggle:Boolean = false
    (read,write)

    A button with a toggle value of true will change its selected state when the button is "clicked".

    Instance methods

    handleInput

    function handleInput (
    details:InputDetails, pathToFocus:Array) : Boolean

    Handle input from the game, via controllers or keyboard. The default handleInput will handle standalone and composite components.
    Parameters:
    details :
    An InputDetails object containing details from the interaction.
    pathToFocus:
    A list of children in the focus path that are below this component. Components are responsible for calling handleInput() on the next component in the pathToFocus unless they choose to intercept the call.
    Overrides:

    setSize

    function setSize (
    width:Number, height:Number) : Void

    Sets the width and height of the component at the same time using internal sizing mechanisms.
    Parameters:
    width :
    The new width of the component.
    height:
    The new height of the component.
    Overrides: